home *** CD-ROM | disk | FTP | other *** search
/ Pascal Super Library / Pascal Super Library (CW International)(1997).bin / MEM_UTL / SWEEP / SWEEP.DOC next >
Text File  |  1990-08-01  |  17KB  |  495 lines
  1.  
  2.  
  3.                            Sweep Library User's Manual
  4.                           Copyright (c) 1990 Eric Tauck
  5.                                All Right Reserved
  6.  
  7.      The Sweep Library is a library of routines for managing memory and
  8.      maintaining a heap.  The advantage of the Sweep Library over the heap
  9.      routines built into Turbo Pascal or Turbo C is that the Sweep Library
  10.      never suffers from memory fragmentation.  The Sweep Library is ideal
  11.      for applications that repeatedly allocate, deallocate, and resize
  12.      blocks of memory.
  13.  
  14.      The Sweep Library is available for Turbo C and Turbo Pascal.  The
  15.      Turbo C version should work with all versions of Turbo C and all
  16.      memory models except tiny.  The Turbo C version may also work with
  17.      other compilers that support standard LIB files and Pascal calling
  18.      conventions.  The Turbo Pascal version was compiled with Turbo Pascal
  19.      version 5.5 and should work with Turbo Pascal versions 5.0 and 5.5.
  20.  
  21.      The Sweep Library is shareware.  If you wish to continue using this
  22.      library after trying it out, please register your copy for $10 (US
  23.      funds, payable to Eric Tauck).  For an additional $15 dollars (i.e., a
  24.      total of $25) you can receive the Sweep Library source code (for both
  25.      Turbo C and Turbo Pascal).  The source code is written in TASM 2.0
  26.      assembly language.  Both 5.25" and 3.5" disk formats are available.
  27.  
  28.        Eric Tauck
  29.        1304 Deerpass Road
  30.        Marengo, IL 60152
  31.        U.S.A
  32.  
  33.        Compuserve: 72457,1557
  34.        GEnie: E.TAUCK
  35.        Internet: 72457.1557@compuserve.com
  36.  
  37.  
  38.                             Sweep Library Description
  39.                             -------------------------
  40.  
  41.      The necessary files for Turbo C are:
  42.  
  43.        SWEEP.LIB
  44.        SWEEP.H
  45.  
  46.      The Sweep Library routines are included in a Turbo C program by using
  47.      the #include statement and linking the library file with your compiled
  48.      program:
  49.  
  50.        #include "sweep.h"
  51.  
  52.      and compile as:
  53.  
  54.        tcc myprog sweep.lib
  55.  
  56.      The only file necessary for Turbo Pascal is:
  57.  
  58.        SWEEP.TPU
  59.  
  60.      The Sweep Library routines are included in a Turbo Pascal program by
  61.      using the USES statement:
  62.  
  63.        USES Sweep;
  64.  
  65.      A heap is created with the HeapInit or HeapInitBlk routines.  These
  66.      routines require the address and size of a memory block in which to
  67.      create the heap.  The farcoreleft and farmalloc in Turbo C provide
  68.      ideal functions for allocating a block of memory for the heap:
  69.  
  70.        /* Turbo C */
  71.  
  72.        #include "sweep.h"
  73.  
  74.        void far *base;               /* 'far' only for small/medium mdls */
  75.        unsigned long size;
  76.        size = farcoreleft();         /* bytes available */
  77.        base = farmalloc (size);      /* allocate memory */
  78.        HeapInit (base, size);        /* create heap */
  79.  
  80.      Though you could use the MaxAvail and GetMem routines in Turbo Pascal,
  81.      you would be limited to a heap of 64K (because GetMem will not
  82.      allocate blocks larger than 64K).  This limitation can be overcome by
  83.      using three special Turbo Pascal routines provided in the Sweep unit:
  84.      DosAvail, DosAlloc, and DosFree.  These functions allocate memory
  85.      directly from the operating system rather than the Turbo Pascal heap
  86.      manager and are not restricted to 64K.  Since the Turbo Pascal heap
  87.      manager usually takes all available memory, you must use the $M
  88.      directive to make some memory available:
  89.  
  90.  
  91.  
  92.        { Turbo Pascal }
  93.  
  94.        {$M 16384,0,0}                { tell TP not to use any extra mem. }
  95.        USES Sweep;
  96.  
  97.        VAR
  98.          base: Pointer;
  99.          size: LongInt;
  100.        BEGIN
  101.          size := DosAvail;           { bytes available }
  102.          base := DosAlloc (size);    { allocate memory }
  103.          HeapInit (base, size);      { create heap }
  104.  
  105.      Once the heap has been created, you can allocate memory with HeapAlloc
  106.      and release memory with HeapFree.  HeapAlloc does not return an
  107.      address to the allocated memory, but rather a 16-bit handle.  This
  108.      handle type is called HeapHandle and is used by all the heap
  109.      management routines.  Memory blocks are accessed by retrieving their
  110.      address with HeapAddr and assigning this address to a pointer:
  111.  
  112.        /* Turbo C */
  113.        /* create an array and zero all elements */
  114.        /* the explicit fars are only needed for small or medium models */
  115.  
  116.        typedef int ArrayType [1000];
  117.  
  118.        HeapHandle MyArrayPtr;
  119.        ArrayType far *MyArray;
  120.        int i;
  121.  
  122.        MyArrayPtr = HeapAlloc (sizeof (ArrayType));      /* allocate */
  123.        MyArray = (ArrayType far *)HeapAddr (MyArrayPtr); /* get address */
  124.  
  125.        for (i = 0; i < 1000; i++) (*MyArray)[i] = 0; /* zero array */
  126.  
  127.        { Turbo Pascal }
  128.        { create an array and zero all elements }
  129.  
  130.        TYPE
  131.          ArrayType = ARRAY [1..1000] OF Integer;
  132.        VAR
  133.          MyArrayPtr: HeapHandle;
  134.          MyArray: ^ArrayType;
  135.          i: Integer;
  136.        BEGIN
  137.          MyArrayPtr := HeapAlloc (SizeOf (ArrayType));  { allocate }
  138.          MyArray := HeapAddr (MyArrayPtr);              { get address }
  139.  
  140.          FOR i := 1 TO 1000 DO MyArray^[i] := 0;        { zero array }
  141.  
  142.      A special handle value is used to indicate an error.  In C it's called
  143.      SWEEP_NULL and in Pascal it's called SWEEP_NIL.  You can also check
  144.      for an error by calling HeapResult.
  145.  
  146.      When a memory block is allocated or resized, the address of other
  147.      blocks may change.  This is a result of maintaining an unfragmented
  148.      heap.  The address of a block returned by HeapAddr is only valid until
  149.      the next time the heap is manipulated.
  150.  
  151.  
  152.      A limitation of the Sweep Library heap routines is that there is a
  153.      fixed number of blocks that can be allocated.  HeapInit sets the
  154.      maximum number of blocks to about 1/64 of the available memory space.
  155.      The maximum number of blocks can be explicitly defined with
  156.      HeapInitBlk.
  157.  
  158.      You can use the Sweep Library pointer manipulation routines to access
  159.      data structures greater than 64K in Turbo Pascal.  If you calculate
  160.      the 32 bit offset of an element within a large data structure, you can
  161.      add the offset to the base address with the PointerAdd function, for
  162.      instance:
  163.  
  164.        { Turbo Pascal }
  165.        { create array of 50000 integers and zero all elements }
  166.  
  167.        CONST
  168.          MyArrayDim = 50000;
  169.          MyArrayElem = SizeOf (Integer);
  170.        VAR
  171.          MyArrayPtr: HeapHandle;
  172.          IntPtr: ^Integer;
  173.          i: Word;
  174.        BEGIN
  175.          MyArrayPtr := HeapAlloc (MyArrayDim * MyArrayElem); { allocate }
  176.  
  177.          FOR i := 1 TO 1000 DO
  178.            BEGIN
  179.              IntPtr := PointerAdd (HeapAddr (MyArrayPtr),
  180.                                    LongInt(i - 1) * LongInt(MyArrayElem));
  181.              IntPtr^ := 0;
  182.            END;
  183.  
  184.      You can use the same technique to access large data structures in
  185.      Turbo C.
  186.  
  187.  
  188.                               Sweep Routine Summary
  189.                               ---------------------
  190.  
  191.      PointerNormal    normalize a pointer
  192.      PointerDenormal  denormalize a pointer
  193.      PointerAdd       add an offset to a pointer
  194.      PointerSub       subtract an offset from a pointer
  195.  
  196.      PointerValue     convert a pointer to a linear value
  197.      PointerDiff      calculate the difference between two pointers
  198.  
  199.      CopyForward      forward copy a memory block
  200.      CopyBackward     reverse copy a memory block
  201.  
  202.      HeapInit         initialize a heap
  203.      HeapInitBlk      initialize a heap with a block count
  204.  
  205.      HeapCurrent      return the current heap address
  206.      HeapSelect       switch to a new heap
  207.      HeapMemory       return the bytes available
  208.      HeapBlocks       return the blocks available
  209.  
  210.      HeapShrink       reduce the size of a heap
  211.      HeapExpand       increase the size of a heap
  212.  
  213.      HeapAlloc        allocate a memory block
  214.      HeapResize       resize a memory block
  215.      HeapFree         free a memory block
  216.      HeapSize         return the size of a memory block
  217.      HeapAddr         return the address of a memory block
  218.  
  219.      HeapResult       return the error code of the last operation
  220.  
  221.      DosAvail         return available system memory (Turbo Pascal only)
  222.      DosAlloc         allocate system memory (Turbo Pascal only)
  223.      DosFree          free system memory (Turbo Pascal only)
  224.  
  225.  
  226.                            Sweep Routine Descriptions
  227.                            --------------------------
  228.  
  229.      Though all the pointer values accepted and returned by the Turbo C
  230.      functions are listed as type 'far', all of the routines except
  231.      PointerDenormal (which always returns a far pointer) will also work
  232.      with huge pointers.  A 'far' modifier for pointer variables is only
  233.      necessary when using the small or medium memory models.  A 'huge' or
  234.      'near' modifier is never necessary.
  235.  
  236.      Many of the Turbo C routines return a value when the Turbo Pascal
  237.      equivalents don't.  Ignore any return value descriptions for Turbo
  238.      Pascal PROCEDURE types.
  239.  
  240.      CopyForward
  241.  
  242.        - void far * CopyForward (void far *d, void far *s, unsigned long c)
  243.  
  244.        - PROCEDURE CopyForward (d, s: Pointer; c: LongInt)
  245.  
  246.        Copy a contiguous block of memory.  The block may be greater than
  247.        64K bytes.  The copy operation is started from the beginning of the
  248.        block, so an overlapping copy will only work if the destination is
  249.        at a lower address than the source.  If the source and destination
  250.        do not overlap, this function has the same effect as CopyBackward.
  251.  
  252.      CopyBackward
  253.  
  254.        - void far* CopyBackward (void far *d, void far *s, unsigned long c)
  255.  
  256.        - PROCEDURE CopyBackward (d, s: Pointer; c: LongInt)
  257.  
  258.        Copy a contiguous block of memory.  The block may be greater than
  259.        64K bytes.  The copy operation is started from the end of the block,
  260.        so an overlapping copy will only work if the destination is at a
  261.        higher address than the source.  If the source and destination do
  262.        not overlap, this function has the same effect as CopyForward.
  263.  
  264.      DosAlloc
  265.  
  266.        - FUNCTION DosAlloc (s: LongInt): Pointer;
  267.  
  268.        Allocate system memory.  Memory must be made available using the $M
  269.        directive.  For instance {$M 16000,4000,4000} allocates 16000 bytes
  270.        for the stack and 4000 bytes for the Turbo Pascal heap.  All
  271.        remaining system memory may be allocated by DosAlloc.  This function
  272.        is only available in Turbo Pascal.
  273.  
  274.      DosAvail
  275.  
  276.        - FUNCTION DosAvail: LongInt;
  277.  
  278.        Return available system memory.  Use this function find the largest
  279.        block available for DosAlloc.  This function is only available in
  280.        Turbo Pascal.
  281.  
  282.  
  283.  
  284.      DosFree
  285.  
  286.        - PROCEDURE DosFree (p: Pointer);
  287.  
  288.        Free allocated system memory.  Use this function to release memory
  289.        allocated with DosAlloc.  This function is only available in Turbo
  290.        Pascal.
  291.  
  292.      PointerAdd
  293.  
  294.        - void far * PointerAdd (void far *p, unsigned long o)
  295.  
  296.        - FUNCTION PointerAdd (p: Pointer; o: LongInt): Pointer;
  297.  
  298.        Add an offset to a far pointer.  The resulting address is
  299.        normalized.
  300.  
  301.      PointerDiff
  302.  
  303.        - unsigned long PointerDiff (void far *p1, void far *p2)
  304.  
  305.        - FUNCTION PointerDiff (p1, p2: Pointer): LongInt;
  306.  
  307.        Calculate the difference between two far pointers.  The result is a
  308.        standard 32 bit signed value (not a pointer).
  309.  
  310.      PointerDenormal
  311.  
  312.        - void far * PointerDenormal (void far *p)
  313.  
  314.        - FUNCTION PointerDenormal (p: Pointer): Pointer;
  315.  
  316.        Denormalize a far pointer.  As much of the segment of an address as
  317.        possible is transferred to the offset.  This function does the
  318.        opposite of PointerNormal.  The result is always a far pointer, even
  319.        when using the huge memory model.
  320.  
  321.      PointerNormal
  322.  
  323.        - void far * PointerNormal (void far *p)
  324.  
  325.        - FUNCTION PointerNormal (p: Pointer): Pointer;
  326.  
  327.        Normalize a far pointer.  As much of the offset of an address as
  328.        possible is transferred to the segment.  This function does the
  329.        opposite of PointerDenormal.
  330.  
  331.      PointerSub
  332.  
  333.        - void far * PointerSub (void far *p, unsigned long o)
  334.  
  335.        - FUNCTION PointerSub (p: Pointer; o: LongInt): Pointer;
  336.  
  337.        Subtract an offset from a far pointer.  The resulting address is
  338.        normalized.
  339.  
  340.  
  341.  
  342.      PointerValue
  343.  
  344.        - unsigned long PointerValue (void far *p)
  345.  
  346.        - FUNCTION PointerValue (p: Pointer): LongInt;
  347.  
  348.        Return the 32 bit linear value equivalent of a far pointer.  This
  349.        function is used to calculate the difference between two far
  350.        pointers.
  351.  
  352.      HeapAddr
  353.  
  354.        - void far * HeapAddr (HeapHandle b)
  355.  
  356.        - FUNCTION HeapAddr (b: HeapHandle): Pointer;
  357.  
  358.        Return the address of a heap memory block.
  359.  
  360.      HeapAlloc
  361.  
  362.        - HeapHandle HeapAlloc (unsigned long s)
  363.  
  364.        - FUNCTION HeapAlloc (s: LongInt): HeapHandle;
  365.  
  366.        Allocate a memory block from the heap.  Return the block handle or
  367.        SWEEP_NULL (Turbo C) or SWEEP_NIL (Turbo Pascal) if error.  's' is
  368.        the number of bytes to allocate.
  369.  
  370.      HeapMemory
  371.  
  372.        - unsigned long HeapMemory (void)
  373.  
  374.        - FUNCTION HeapMemory: LongInt;
  375.  
  376.        Return the total available bytes in the heap.
  377.  
  378.      HeapBlocks
  379.  
  380.        - unsigned HeapBlocks (void)
  381.  
  382.        - FUNCTION HeapBlocks: Word;
  383.  
  384.        Return the number of available memory blocks in the heap.
  385.  
  386.      HeapCurrent
  387.  
  388.        - void far * HeapCurrent (void)
  389.  
  390.        - FUNCTION HeapCurrent: Pointer;
  391.  
  392.        Return the address of the current heap.
  393.  
  394.  
  395.  
  396.      HeapExpand
  397.  
  398.        - void HeapExpand (unsigned long s)
  399.  
  400.        - PROCEDURE HeapExpand (s: LongInt)
  401.  
  402.        Increase the size of the current heap.  The heap is expanded at its
  403.        end by 's' bytes.  Note: You are responsible for making sure that
  404.        there is enough available memory to perform this operation.
  405.  
  406.      HeapFree
  407.  
  408.        - void HeapFree (HeapHandle b)
  409.  
  410.        - PROCEDURE HeapFree (b: HeapHandle)
  411.  
  412.        Free a heap memory block.
  413.  
  414.      HeapInit
  415.  
  416.        - void far * HeapInit (void far *h, unsigned long s)
  417.  
  418.        - PROCEDURE HeapInit (h: Pointer; s: LongInt)
  419.  
  420.        Initialize a heap at the given address.  The minimum heap size is 12
  421.        bytes. The maximum number of blocks is calculated as the heap size
  422.        divided by 64 with a minimum of 32 and a maximum of about 21800.
  423.        The newly initialized heap becomes the current heap and the original
  424.        heap address is returned.  The function HeapInitBlk is identical
  425.        except that the maximum number of memory blocks is specified by the
  426.        user rather than being calculated.  'h' is the base heap address and
  427.        's' is the number of bytes allocated to the heap.
  428.  
  429.      HeapInitBlk
  430.  
  431.        - void far * HeapInitBlk (void far *h, unsigned long s, unsigned b)
  432.  
  433.        - PROCEDURE HeapInitBlk (h: Pointer; s: LongInt; b: Word)
  434.  
  435.        Initialize a heap at the given address.  The minimum heap size is 12
  436.        bytes. The maximum number of blocks may be adjusted down, so use
  437.        HeapBlocks to find the actual number initialized.  The newly
  438.        initialized heap becomes the current heap and the original heap
  439.        address is returned.  The function HeapInit is identical except that
  440.        the maximum number of blocks is calculated rather than being
  441.        specified by the user.   'h' is the base heap address, 's' is the
  442.        number of bytes allocated to the heap, and 'b' is the number of
  443.        blocks to assign to the heap.
  444.  
  445.      HeapResize
  446.  
  447.        - HeapHandle HeapResize (HeapHandle b, unsigned long s)
  448.  
  449.        - PROCEDURE HeapResize (b: HeapHandle; s: LongInt)
  450.  
  451.        Resize a heap memory block.  Returns the block handle or SWEEP_NULL
  452.        if error.
  453.  
  454.  
  455.  
  456.      HeapResult
  457.  
  458.        - int HeapResult (void)
  459.  
  460.        - FUNCTION HeapResult: Word;
  461.  
  462.        Return the error code of the last heap operation (or zero if no
  463.        error).  The error code is reset with each operation (including this
  464.        one).  An error code of 1 is out of memory and 2 is out of memory
  465.        blocks.  The symbolic constants SWEEP_NOERROR, SWEEP_OUTOFBLOCKS,
  466.        and SWEEP_OUTOFMEMORY have been defined to check for these return
  467.        values.
  468.  
  469.      HeapSelect
  470.  
  471.        -  void far * HeapSelect (void far *h)
  472.  
  473.        -  PROCEDURE HeapSelect (h: Pointer)
  474.  
  475.        Switch to a previously initialized heap.  Returns the current heap
  476.        address.
  477.  
  478.      HeapShrink
  479.  
  480.        - void HeapShrink (unsigned long s)
  481.  
  482.        - PROCEDURE HeapShrink (s: LongInt)
  483.  
  484.        Decrease the size of the heap.  The heap is adjusted at its end by
  485.        's' bytes.  Note: the heap MUST have at least 's' bytes free.
  486.  
  487.      HeapSize
  488.  
  489.        - unsigned long HeapSize (HeapHandle b)
  490.  
  491.        - FUNCTION HeapSize (b: HeapHandle): LongInt;
  492.  
  493.        Return the size of a heap memory block.
  494.  
  495.